Add simplified architecture diagrams for traffic flow and config changes #3557
Conversation
|
Hi @sarthyparty! Thanks for opening this pull request! |
github-actions
bot
added
documentation
|
✅ All required contributors have signed the F5 CLA for this PR. Thank you! |
|
I have hereby read the F5 CLA and agree to its terms |
Co-authored-by: salonichf5 <146118978+salonichf5@users.noreply.github.com>
Co-authored-by: salonichf5 <146118978+salonichf5@users.noreply.github.com>
|
can we rename the folder to |
| - **Gateway**: Defines entry points for traffic | ||
| - **HTTPRoute**: Defines HTTP routing rules | ||
| - **GRPCRoute**: Defines gRPC routing rules | ||
| - **TLSRoute**: Defines TLS routing rules |
There was a problem hiding this comment.
We also implement BackendTLSPolicy and GatewayClass. To avoid having to keep updating this list as more resources get added, we could link to https://docs.nginx.com/nginx-gateway-fabric/overview/gateway-api-compatibility/ instead.
|
|
||
| ### Control Plane Security | ||
|
|
||
| - **Full Kubernetes API access** (to watch resources) |
There was a problem hiding this comment.
Not technically full access. We use RBAC to limit to just the resources and permissions we care about.
| @@ -0,0 +1,83 @@ | |||
| # NGINX Gateway Fabric Architecture | |||
|
|
|||
| This guide explains how NGINX Gateway Fabric works in simple terms. | |||
There was a problem hiding this comment.
I think it could also be worth linking to https://docs.nginx.com/nginx-gateway-fabric/overview/gateway-architecture/ for more details on the architecture.
| - **nginx.conf**: Main configuration | ||
| - **servers.conf**: Virtual server definitions | ||
| - **upstreams.conf**: Backend service definitions | ||
| - **maps.conf**: Request routing maps |
There was a problem hiding this comment.
These aren't technically the conf files that we generate. It's an ever-changing list, so I wouldn't bother listing them here.
| ```mermaid | ||
| %%{init: {'theme':'dark', 'themeVariables': {'fontSize': '16px', 'darkMode': true, 'primaryColor': '#4f46e5', 'primaryTextColor': '#e5e7eb', 'primaryBorderColor': '#6b7280', 'lineColor': '#9ca3af', 'secondaryColor': '#1f2937', 'tertiaryColor': '#374151', 'background': '#111827', 'mainBkg': '#1f2937', 'secondBkg': '#374151', 'tertiaryTextColor': '#d1d5db'}}}%% | ||
| graph LR | ||
| %% Simple traffic flow | ||
| USER[👤 User] | ||
|
|
||
| subgraph "Kubernetes Cluster" | ||
| NGINX[🌐 NGINX] | ||
|
|
||
| subgraph "Your Apps" | ||
| SVC1[🔵 user-service] | ||
| SVC2[🔵 order-service] | ||
| POD1[Pod A] | ||
| POD2[Pod B] | ||
| POD3[Pod C] | ||
| end | ||
| end | ||
|
|
||
| %% Simple flow | ||
| USER --> NGINX | ||
| NGINX --> SVC1 | ||
| NGINX --> SVC2 | ||
| SVC1 --> POD1 | ||
| SVC1 --> POD2 | ||
| SVC2 --> POD3 | ||
|
|
||
| %% Dark-friendly styling | ||
| style USER fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#1f2937 | ||
| style NGINX fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#ffffff | ||
| style SVC1 fill:#10b981,stroke:#059669,stroke-width:2px,color:#ffffff | ||
| style SVC2 fill:#10b981,stroke:#059669,stroke-width:2px,color:#ffffff | ||
| ``` |
There was a problem hiding this comment.
nginx technically routes directly to the Pods, not through the Service. We use the Service to get information about the Pods.
| ```text | ||
| NGINX Gateway: | ||
| ├── Receives request from user | ||
| ├── Applies SSL termination |
There was a problem hiding this comment.
(only if a user configures it to do so)
| ### Path-Based Routing | ||
|
|
||
| ```nginx | ||
| # Generated from HTTPRoute resources | ||
| location /users { | ||
| proxy_pass http://user-service; | ||
| } | ||
|
|
||
| location /orders { | ||
| proxy_pass http://order-service; | ||
| } | ||
|
|
||
| location /products { | ||
| proxy_pass http://product-service; | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
| ### Host-Based Routing | ||
|
|
||
| ```nginx | ||
| # Different hosts route to different services | ||
| server { | ||
| server_name api.example.com; | ||
| location / { | ||
| proxy_pass http://api-service; | ||
| } | ||
| } | ||
|
|
||
| server { | ||
| server_name admin.example.com; | ||
| location / { | ||
| proxy_pass http://admin-service; | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
These should be combined. Every route we perform uses both a hostname and a path.
| ```text | ||
| Resources Created: | ||
| ├── Deployment: nginx-gateway-{gateway-name} | ||
| ├── Service: nginx-gateway-{gateway-name} | ||
| ├── ConfigMap: nginx-config-{gateway-name} | ||
| ├── ServiceAccount: nginx-gateway-{gateway-name} | ||
| └── Secrets: TLS certificates (if needed) | ||
| ``` |
There was a problem hiding this comment.
There are a handful of others resources we create. I don't expect them to all be listed, but I don't want a dev to be confused and think that this list is all we create.
Proposed changes
Add simplified architecture diagrams for traffic flow and config changes.
Problem: The current architecture documentation for NGF is written and presented in a way for a new user or developer to be able to understand.
Solution: Adding new diagrams and explanations for how traffic flows and how config changes are applied and the lifecycle of a gateway.
Please focus on (optional): If you any specific areas where you would like reviewers to focus their attention or provide
specific feedback, add them here.
Closes #3545
Checklist
Before creating a PR, run through this checklist and mark each as complete.
Release notes
If this PR introduces a change that affects users and needs to be mentioned in the release notes,
please add a brief note that summarizes the change.